Suzy B Software 2/Suzy B Software CD-ROM 2 (1994).iso/prntutil/ascreen/engintro.txt

Text File | 1995-04-25 | 13KB | 276 lines

Introduction to ASCREEN 3.2
===========================

Preface
-------
ASCREEN is a DVI previewer for Atari computers. Refer to the ANNOUNCE
and README files to find out how magnificent it is :-) This short
document explains some aspects of ASCREEN. Its main purpose is to
soothe the author's conscience about not providing a proper English
manual. (Most software products have English manuals only and no
German. So there!)

Installing ASCREEN
------------------
ASCREEN is adaptable enough to fit into just about any TeX installation on
the Atari. However, it must be adjusted to your system. This is how:

1. Copy the disk. I mean it. COPY THE DISK. NOW.
2. You need to put the program (ASCREEN.PRG) where your TeX wants to find
   DVI drivers. Look for where your other previewer is and put ASCREEN.PRG
   right beside it.
3. You also need a resource file. If you're reading this document
   instead of the German manual, you don't want ASCREEN.RSC. It's all
   in German. Use ASCRNENG.RSC instead. That one's going to make sense
   to you. Put it right beside ASCREEN.PRG and call it ASCREEN.RSC.
4. Depending on which TeX implementation you're using, select a setup file
   and put it near ASCREEN.PRG under the name of ASCREEN.SET. Use

    ASCREEN.SET    if you're using Stefan Lindner's TeX
    ASTRUNK.SET    if you're using Christoph Strunk's csTeX

   The point of the exercise is that ASCREEN needs to know how font names
   are constructed in the TeX you're using. For example, cmr10 at 12pt
   is
    ...\res101.scr\mag____1.200\cmr10.pk    in Lindner's TeX
    ...\font0115\cmr10.pk            in csTeX

   Wilder schemes exist, too. Look at ASCREEN.SET to see a couple of them.
5. The ellipsis in the example stands for `wherever fonts are on YOUR
   system'. You have to fix that as well. Either look at ASCREEN.SET
   (the one you just created) with an editor, locate the line that says
   `fontpath' and insert the appropriate path there. Or start ASCREEN.PRG,
   select the `Paths' form from the `Options' menu and edit the font path.
6. Now you should be all set. There's loads of stuff that you can customise
   either using the forms in the `Options' menu or by editing the
   setup file. We'll be looking at some of that later.

Running ASCREEN
---------------
You can invoke ASCREEN from the desktop and then `Open' a DVI file
from the `File' menu. You can also install ASCREEN as an application
for DVI files so it is run whenever you double click on a file that
has the .DVI extension. You can run ASCREEN from a command line shell
that lets you run GEM programs (many of them do, e. g.,
GEMINI/Mupfel). Or you can call ASCREEN from a TeX shell if you're
using one (like the CSTEX program in csTeX).

First of all, ASCREEN reads a setup file, commonly called ASCREEN.SET.
The name of this file is taken from the ASCREENSET environment
variable if it exists. Or you can specify the setup file name on the
command line, like `ascreen &foo.set bar'. This lets you have
different setup files for various circumstances. Everything you can
say in a setup file, you can also say on the command line, and vice
versa.

Previewing DVI files with ASCREEN
---------------------------------
Once you have started ASCREEN and loaded a DVI file, the first page of
the file will be displayed in a window. Use the following procedures
to move about:

- Scroll bars and arrows operate as usual.
- The cursor keys are equivalent to the scroll arrows. Shifted, they are
  equivalent to clicking into the grey areas on the scroll bars.
- For organ players, the 1,2,3,5 keys on the keypad are equivalent to
  the shifted cursor keys. The 7,8,9,) keys are equivalent to the unshifted
  cursor keys. The Clr/Home key warps to the top left corner of the page.
- You may also drag the window contents directly by holding down the
  Alternate key while you're clicking the left button inside a window.
  Hold down Shift instead of Alternate for accelerated scrolling.

You can go from page to page by the following methods:

- Clicking and holding down the left button inside a window pops up a
  menu. The first two entrys let you move forward or back a page. The third
  will pop up a form which will let you enter a page number to go to.
- Use the + and - keys on the keypad to move forward or back. Use the
  0 key on the keybad to pop up the form.

If you're at the bottom of a page and move forward, you'll end up at
the top of the next page. Similarly, if you're at the top of a page
and move back, you'll be put at the bottom of the previous page. This
is called `smart paging', and you can switch it off if you don't like it.

The Enter key will move down just like the 2 key until you're at the
bottom of the page. Then it'll move over to the next page like the +
key. The . key on the keypad does the same backwards. This is called
`magic Enter' and you can switch that off as well.

Now for some special tricks:

- Use the popup menu to shrink the page you're looking at by a factor of
  2 or 3. You're not going to be able to read anything but you'll be able
  to have a look at a complete page. The shrunken page will be
  displayed in a new window where you can move around, back and forth
  and so on independently. (You can't shrink it any further, though.)
- You can also shrink two adjacent pages to look at how your document
  might look in a book. This is on the menu as well.
- You can use the ( key on the keypad for single-page and the 4 key for
  double page shrinking from the keyboard. (Mnemonic: the 1 key & co.
  move a lot. The 4 key shrinks a lot.)
- The shrink factor can be selected from the DVI options menu. The /
  and * keys on the keypad select a factor of 2 and 3, respectively.
- A special `recto-verso mode' can be enabled for double-page shrinking
  by either selecting it from the popup menu or toggling it with the 6
  key on the keypad. It will try to sensibly page backward and forward
  in steps of two pages instead of one, just like in a book or journal.
  The default mode can be selected from the DVI options menu.

The menu bar
------------
These are the menu bar entries and what they do:

About ASCREEN...    You know that one.
Open...            Open a new DVI file, replacing the one currently
            displayed, if any.
Reread            Reread the current DVI file. Most useful in a
            multitasking environment.
Quit program        You know that one, too.
New window        Open a new window on the page currently in the top
            window.
Window on page...    Prompt for a page number, then open a new window
            on that page.
Next window        Put another window on top. Eventually this cycles
            through all windows.
Close window        Close the top window.
Statistics        Display memory statistics.
Help            Display a help dialog.
GEM Options...        Forms showing various options you can
DVI Options...            customise.
Page Format...        Form to override (enlarge) DVI page size
Memory...        Form to set memory usage parameters
Paths...        Form to set file access paths and parameters
Restore...        Restore setup from file
Save...            Save setup to file

Options
-------
Here's a list of all the things you can customise in the setup file,
together with the equivalent command line options.

Setup file            Command line    Remarks
-------------------------------------------------------------------------
cacheahead [N, 1, D]        -A    Cache 1 page ahead of current
cachepages [N, 5, M]        -p #    maximal number of pages cached
colors [N, 1, G]        -c #    Colors; 256*background+foreground
dvibuflimit [N, 20000, M]    N/A    max length of DVI files that will
                    be read whole on opening
dvibufsize [N, 8192, M]        N/A    buffer size when reading DVI file
dvipath [dir, d:\texout, P]    -D dir    Standard directory for DVI files
emergencyfont [font, cmr10]    N/A    font used if nothing else found
emergencysize [dimen, 10pt]    N/A    `at size' of emergencyfont
extension [string, scr]        -e str    %e in fontname template
feeponerror [N, 1, G]        N/A    feep when printing error message?
focus [Window/Pointer, Window, G] N/A    Where keyboard commands go: active
                    Window or window with Pointer in it
fontname [template,, P]        -z    Template for font names. See below
fontpath [path, d:\prtfonts, P]    -F path    List of font directories/FLIBs
glyphmem [N, 64000, M]        N/A    Memory for unpacking glyphs
grafpath [path, d:\graphics, P]    -G path    List of IMG file directories
hresolution [N, 101, P]        -r #    horizontal resolution of fonts
hypertex [N, 1, D]        N/A    HyperTeX \special cmds interpreted
leftmargin [dimen, 0pt, S]    -H dim    Width of left margin
logging    [N, 0, D]        -l    write messages to log file?
magnification [mag, magstep0],    -M mag    override DVI file magnification
maxfonts [N, 32, M]        -Z #    max number of simultaneous PK files
memcheck [N, 0, G]        N/A    display free mem in menu bar
missingfile [file, missing.fnt, P] N/A    file name for missing fonts list
missingstyle [Lindner/Strunk, Lindner, P] N/A style for missing fonts list
movebyenter [N, 1, D]        -m    use `magic Enter' movements
msgraise [N, 1, G]        N/A    raise message window on output
msgwindow [geometry, 256x160+320+154] -w geo    geometry of message window
nokeypress            -J    ignored for compatibility
pageheight [dimen, 0pt, S]    -y dim    maximal height of bitmap or 0
pagetable [N, 1, D]        N/A    remember DVI page positions?
pagewidth [dimen, 0pt, S]    -x dim    maximal width of bitmap or 0
rightbutton [N, 1, G]        N/A    use right button to drag pages
rvmode [N, 0, G]        N/A    r/v mode default for 2-page shrinks?
savemem                N/A    ignored for compatibility
showgraphics [N, 1, D]        -I    actually show IMG graphics?
shrinkfactor [2/3, 2, D]    -f #    default shrink factor
smartpaging [N, 1, D]        N/A    see above
stats                N/A    ignored for compatibility
tfmpath                N/A    reserved for future expansion
topmargin [dimen, 0pt, S]    -V dim    Size of top margin
usedesk [N, 0, G]        -d    first page in borderless big window?
verbose [N, 0, D]        -v    lots of explanations?
vfpath                N/A    reserved for future expansion
vresolution [N, 101, P]        -r    vertical resolution of fonts

Information in brackets: [type, default, form] where `type' is

    N for a number,
    dimen for a dimension (as in TeX),
    dir for a directory name,
    font for a font name,
    template for a font name template (see below),
    path for a list of directory names separated by commas,
    mag for a magnification (as in TeX),
    file for a file name,
    geometry for a geometry specification (width x height
        [+/-] xoffset [+/- yoffset], as in X11).

`form', if present, is where you can set the value from within ASCREEN:

    G: GEM options form,
    D: DVI options form,
    S: page dimensions form,
    M: memory form,
    P: paths form.

`N/A' as a command line option means that this value is not accessible
directly from the command line. However, any setup variable may be set
using the special `-s' option, as in `-s rvmode=1'.

A font name template works like a printf() format string (for those of
you who know C). The idea is that certain magic `escapes' are replaced
by bits that help in constructing a font name. Look at the original
ASCREEN.SET to get the idea. The escape sequences are:

    %f    font name (sans .pk suffix)
    %m    magnification in per mille as an integer
    %M    magnification as a real number (e. g., 1.728)
    %r    (horizontal) device resolution in dots per inch
    %R    %r times 5
    %p    (horizontal) device resolution in dpi multiplied by the
        magnification
    %P    %p times 5
    %e    value of the `extension' variable

A field width and precision may be interpolated between the % and the
letter. A tilde (~) at the beginning of the template is substituted by
the current directory from the font path.  So, for example, the
default value of `fontname',

    ~\res%r.%e\mag____%5.3M\%f.pk

evaluates to `d:\texfonts\res101.scr\mag____1.200\cmr10.pk' for a 10pt
Computer Modern Roman font at magstep 1, if `d:\texfonts' is being
searched.

Extras
------
Some programs and files are included with the distribution. These are:

ALAUNCH
This program demonstrates how to control ASCREEN via the GEM message
pipe. It is designed to run under MultiGEM and can be installed as the
application for DVI files. If a DVI file is double-clicked, ALAUNCH
checks whether an ASCREEN process is running. If so, it is sent a
message to open the new file instead of the one it currently displays.
If not, an ASCREEN process is launched. Includes C source code.

FONTLIST
Lists the fonts used in a document. A variety of formats can be selected.
Includes portable C source code.

RESOURCE
Helpful things for resource hackers, such as an RCS definition and C
header file. ASCRNIC.RSC contains the official ASCREEN icons.

HYPERTEX
Demonstrates the experimental hypertext support in ASCREEN.

Have fun. And don't forget that postcard!